/**
 * 认证服务接口
 * 
 * 功能说明：
 * - 定义用户认证相关的核心业务逻辑接口
 * - 提供用户登录、注册、令牌刷新等认证功能
 * - 支持用户信息管理（密码修改、资料更新）
 * - 提供注销登录功能，支持令牌失效处理
 * 
 * 业务逻辑：
 * - 用户登录：验证用户身份，生成访问令牌和刷新令牌
 * - 用户注册：创建新用户，分配默认角色，生成认证令牌
 * - 令牌刷新：使用刷新令牌获取新的访问令牌
 * - 注销登录：使当前令牌失效，增强安全性
 * - 密码修改：验证旧密码，更新为新密码
 * - 资料更新：修改用户基本信息（昵称、头像等）
 * 
 * 安全考虑：
 * - 密码使用BCrypt加密存储，确保安全性
 * - 支持多方式登录（用户名、邮箱、手机号）
 * - 令牌包含用户权限信息，支持细粒度权限控制
 * - 提供统一的用户信息管理服务
 * 
 * 微服务集成：
 * - 注册时同步用户信息到用户服务
 * - 支持分布式环境下的用户状态管理
 * - 通过Feign客户端实现服务间通信
 * 
 * @author eCommerce Team
 * @version 1.0
 */
package com.ecommerce.auth.service;

import com.ecommerce.auth.dto.AuthResponse;
import com.ecommerce.auth.dto.ChangePasswordRequest;
import com.ecommerce.auth.dto.LoginRequest;
import com.ecommerce.auth.dto.RegisterRequest;
import com.ecommerce.auth.dto.ServiceLoginRequest;
import com.ecommerce.auth.dto.ServiceLoginResponse;
import com.ecommerce.auth.dto.UpdateProfileRequest;
import com.ecommerce.auth.dto.UserInfoResponse;

import java.util.List;

/**
 * 认证服务接口
 * 定义用户认证和用户信息管理的核心业务逻辑
 */
public interface AuthService {

    /**
     * 用户登录
     * 
     * 功能说明：
     * - 支持用户名、邮箱、手机号三种登录方式
     * - 验证用户密码的正确性
     * - 检查账户状态（是否启用、是否锁定）
     * - 生成访问令牌和刷新令牌
     * - 更新最后登录时间
     * 
     * 安全考虑：
     * - 密码使用BCrypt算法验证，防止时序攻击
     * - 统一错误信息，避免用户枚举攻击
     * - 记录登录时间，用于安全分析
     * 
     * @param loginRequest 登录请求，包含用户名/邮箱/手机号和密码
     * @return 认证响应，包含访问令牌、刷新令牌、用户信息等
     * @throws RuntimeException 当用户名不存在、密码错误或账户状态异常时抛出异常
     */
    AuthResponse login(LoginRequest loginRequest);

    /**
     * 用户注册
     * 
     * 功能说明：
     * - 创建新用户账户，分配默认角色（普通用户）
     * - 对密码进行BCrypt加密处理
     * - 同步用户信息到用户服务（通过Feign客户端）
     * - 生成认证令牌，注册完成后自动登录
     * 
     * 数据验证：
     * - 检查用户名、邮箱的唯一性
     * - 验证密码复杂度（长度、字符类型等）
     * - 验证手机号格式（如提供）
     * 
     * 事务管理：
     * - 使用@Transactional注解，确保数据一致性
     * - 注册失败时自动回滚数据库操作
     * 
     * @param registerRequest 注册请求，包含用户基本信息
     * @return 认证响应，包含访问令牌、刷新令牌、用户信息等
     * @throws RuntimeException 当用户名/邮箱已存在或数据验证失败时抛出异常
     */
    AuthResponse register(RegisterRequest registerRequest);

    /**
     * 刷新访问令牌
     * 
     * 功能说明：
     * - 使用刷新令牌获取新的访问令牌
     * - 验证刷新令牌的有效性和完整性
     * - 保持用户登录状态，避免频繁重新登录
     * 
     * 令牌管理：
     * - 访问令牌过期后，使用刷新令牌获取新令牌
     * - 刷新令牌通常具有更长的有效期（如7天）
     * - 支持令牌续期，提升用户体验
     * 
     * @param refreshToken 刷新令牌，用于获取新的访问令牌
     * @return 新的认证响应，包含新的访问令牌和用户信息
     * @throws RuntimeException 当刷新令牌无效或过期时抛出异常
     */
    AuthResponse refreshToken(String refreshToken);

    /**
     * 注销登录
     * 
     * 功能说明：
     * - 使当前访问令牌失效
     * - 清除用户的登录状态
     * - 可选：将令牌加入黑名单，防止重复使用
     * 
     * 安全考虑：
     * - 立即失效当前令牌，防止被恶意使用
     * - 建议在客户端同时清除本地存储的令牌
     * - 可用于用户主动退出或管理员强制下线
     * 
     * @param token 当前访问令牌，将被标记为失效
     * @throws RuntimeException 当令牌处理失败时抛出异常
     */
    void logout(String token);

    /**
     * 修改用户密码
     * 
     * 功能说明：
     * - 验证当前密码的正确性
     * - 更新为新密码并进行BCrypt加密
     * - 可选：使当前令牌失效，要求重新登录
     * 
     * 安全考虑：
     * - 必须验证当前密码，防止未授权修改
     * - 新密码需要满足复杂度要求
     * - 记录密码修改时间，用于安全审计
     * 
     * @param userId 用户ID，标识要修改密码的用户
     * @param changePasswordRequest 修改密码请求，包含当前密码和新密码
     * @throws RuntimeException 当当前密码错误或新密码不符合要求时抛出异常
     */
    void changePassword(Long userId, ChangePasswordRequest changePasswordRequest);

    /**
     * 更新用户基本信息
     * 
     * 功能说明：
     * - 修改用户的基本信息（昵称、头像、性别、地址等）
     * - 保持用户名、邮箱等关键信息不变
     * - 同步更新用户服务中的用户信息
     * 
     * 数据验证：
     * - 验证输入数据的有效性和格式
     * - 检查图片URL的有效性（如提供）
     * - 确保数据长度符合数据库约束
     * 
     * 事务管理：
     * - 使用@Transactional注解，确保数据一致性
     * - 更新失败时自动回滚数据库操作
     * 
     * @param userId 用户ID，标识要更新信息的用户
     * @param updateProfileRequest 更新用户信息请求，包含要修改的信息
     * @throws RuntimeException 当数据验证失败或服务调用失败时抛出异常
     */
    void updateProfile(Long userId, UpdateProfileRequest updateProfileRequest);

    /**
     * 获取用户基本信息
     * 
     * 功能说明：
     * - 根据用户ID获取用户的基本信息
     * - 用于服务间用户信息同步
     * - 只返回必要的用户字段，不包含敏感信息
     * 
     * 返回信息：
     * - 用户ID、用户名、邮箱、手机号等基本信息
     * - 用户昵称、头像、地址等扩展信息
     * - 用户类型、账户状态等系统信息
     * - 创建时间、更新时间等时间信息
     * 
     * 安全考虑：
     * - 不返回密码等敏感信息
     * - 只返回必要的用户字段
     * - 支持跨服务调用
     * 
     * @param userId 用户ID，标识要获取信息的用户
     * @return UserInfoResponse 用户基本信息响应对象
     * @throws RuntimeException 当用户不存在时抛出异常
     */
    UserInfoResponse getUserInfo(Long userId);

    /**
     * 删除用户账户
     * 
     * 功能说明：
     * - 根据用户名删除用户账户
     * - 用于用户服务注册失败时的回滚操作
     * - 删除用户相关的所有数据（用户信息、角色关联等）
     * 
     * 使用场景：
     * - 用户服务注册失败时的补偿操作
     * - 管理员删除用户账户
     * - 系统维护时的数据清理
     * 
     * 安全考虑：
     * - 只允许服务间调用，不对外暴露
     * - 删除操作不可逆，需要谨慎使用
     * - 记录删除日志，用于审计追踪
     * 
     * @param username 用户名，标识要删除的用户
     * @throws RuntimeException 当用户不存在或删除失败时抛出异常
     */
    void deleteUserByUsername(String username);

    /**
     * 更新用户状态
     * 
     * 功能说明：
     * - 根据用户ID更新用户的启用/禁用状态
     * - 用于管理员对用户账户的状态管理
     * - 状态变更会立即生效，影响用户登录
     * 
     * 业务规则：
     * - 禁用用户：用户无法登录系统，已有的令牌失效
     * - 启用用户：用户可以正常登录系统
     * - 状态变更记录日志，用于审计追踪
     * 
     * 使用场景：
     * - 管理员禁用违规用户账户
     * - 用户服务同步用户状态到认证服务
     * - 系统批量用户状态管理
     * 
     * 安全考虑：
     * - 只允许管理员操作，需要权限验证
     * - 状态变更需要记录操作日志
     * - 禁用操作会立即失效用户令牌
     * 
     * @param userId 用户ID，标识要更新状态的用户
     * @param enabled 启用状态，true为启用，false为禁用
     * @throws RuntimeException 当用户不存在或状态更新失败时抛出异常
     */
    void updateUserStatus(Long userId, Boolean enabled);

    /**
     * 根据用户ID删除用户账户
     * 
     * 功能说明：
     * - 根据用户ID删除用户账户及相关数据
     * - 用于管理员删除指定用户
     * - 删除用户相关的所有数据（用户信息、角色关联、令牌等）
     * 
     * 使用场景：
     * - 管理员删除违规用户账户
     * - 用户注销账户
     * - 系统维护时的数据清理
     * 
     * 安全考虑：
     * - 只允许管理员操作，需要权限验证
     * - 删除操作不可逆，需要谨慎使用
     * - 记录删除日志，用于审计追踪
     * 
     * @param userId 用户ID，标识要删除的用户
     * @throws RuntimeException 当用户不存在或删除失败时抛出异常
     */
    void deleteUserById(Long userId);

    /**
     * 批量删除用户账户
     * 
     * 功能说明：
     * - 批量删除多个用户账户及相关数据
     * - 用于管理员批量删除用户
     * - 删除用户相关的所有数据（用户信息、角色关联、令牌等）
     * 
     * 使用场景：
     * - 管理员批量清理违规用户
     * - 系统维护时的批量数据清理
     * - 用户批量注销
     * 
     * 安全考虑：
     * - 只允许管理员操作，需要权限验证
     * - 删除操作不可逆，需要谨慎使用
     * - 记录删除日志，用于审计追踪
     * - 支持事务处理，确保数据一致性
     * 
     * @param userIds 用户ID列表，标识要删除的用户
     * @throws RuntimeException 当删除失败时抛出异常
     */
    void batchDeleteUsers(List<Long> userIds);

    /**
     * 检查用户名是否存在
     * 
     * 功能说明：
     * - 根据用户名检查用户是否存在于认证服务中
     * - 用于用户删除事件的同步处理
     * - 支持跨服务用户存在性验证
     * 
     * 使用场景：
     * - 用户删除事件监听器验证用户存在性
     * - 服务间用户数据同步验证
     * - 用户注册前的存在性检查
     * 
     * 返回信息：
     * - true: 用户存在
     * - false: 用户不存在
     * 
     * @param username 用户名
     * @return boolean 用户存在性检查结果
     */
    boolean existsByUsername(String username);

    /**
     * 服务登录
     * 
     * 功能说明：
     * - 用于微服务间调用认证服务获取访问令牌
     * - 验证服务身份并返回有效的JWT令牌
     * - 支持服务间安全通信
     * 
     * 验证流程：
     * 1. 验证服务ID和服务密钥的合法性
     * 2. 检查服务是否已注册且状态正常
     * 3. 生成专用于服务间调用的JWT令牌
     * 4. 返回令牌信息，包含有效期
     * 
     * 安全考虑：
     * - 服务密钥需要安全存储和传输
     * - 令牌具有较短的有效期，建议1小时
     * - 令牌包含服务标识，便于权限控制
     * - 支持令牌黑名单机制
     * 
     * @param request 服务登录请求，包含serviceId和serviceKey
     * @return ServiceLoginResponse 服务登录响应，包含访问令牌和有效期
     * @throws RuntimeException 当服务ID或密钥无效时抛出异常
     */
    ServiceLoginResponse serviceLogin(ServiceLoginRequest request);
}